home *** CD-ROM | disk | FTP | other *** search
/ Workbench Design / WB Collection.iso / workbench werkzeuge / clipboard / cliphistory / cliphistory.man < prev    next >
Text File  |  1996-04-07  |  41KB  |  1,023 lines
  1.  
  2.  
  3.    This file describes ClipHistory, version 2.2, a program that adds
  4. a history to the clipboard.
  5.  
  6. Introduction
  7. ************
  8.  
  9.    This is a program that I thought about writing for a long time (a
  10. year or so! :) before I actually implemented it. I first got the idea
  11. when I had used the history feature of PowerSnap (by Nico François)
  12. a little while. I soon realised that it was a very convenient feature.
  13.  
  14.    The problem is that other programs uses the clipboard as well. The
  15. history PowerSnap maintains only applies to the text that
  16. PowerSnap writes to the clipboard, not the ones e.g. my editor
  17. writes. And I thought that it would indeed be useful to have them in a
  18. history too.
  19.  
  20.    One problem with such a history is that it easily can eat up a lot
  21. of memory, since cuts and copies in an editor can be rather large at
  22. times. To remedy this problem, there are several filtering options,
  23. that limits the amount of memory ClipHistory may use. But more about
  24. this later on in this document.
  25.  
  26.    One interesting detail: ClipHistory is a completely system friendly
  27. program, in that it doesn't patch any functions at all (unless you
  28. really want it to! :). It only uses well documented features of the
  29. operating system. This does have a minor drawback: ClipHistory can
  30. miss clips, if several clips are written in a very short time. But this
  31. shouldn't be any problem, I think.. :)
  32.  
  33. Legal information
  34. *****************
  35.  
  36.        ClipHistory is freeware, i.e. copyrighted, freely distributable
  37. software. Feel free to use and copy this program, as long as the
  38. following restrictions are fulfilled:
  39.  
  40.    *  All files are copied without any alterations. If any extra files
  41.      are added, it must be obvious that they don't belong to the
  42.      original distribution, and that they don't need to be included in
  43.      any redistribution.
  44.  
  45.      Exception: So called "BBS ads" may not be added.
  46.  
  47.    *  The copying is done on a non-commercial basis. A small fee to
  48.      cover media costs etc. may be charged.
  49.  
  50.    *  The copier isn't claiming the copyright of this program.
  51.  
  52.    Any exeptions from the above requires a written permission from the
  53. author.
  54.  
  55. No warranty
  56. ===========
  57.  
  58.    THERE IS NO WARRANTY FOR THE PROGRAMS, TO THE EXTENT PERMITTED BY
  59. APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
  60. HOLDER AND/OR OTHER PARTIES PROVIDE THE PROGRAMS "AS IS" WITHOUT
  61. WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
  62. LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  63. PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE
  64. OF THE PROGRAMS IS WITH YOU. SHOULD THE PROGRAMS PROVE DEFECTIVE, YOU
  65. ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  66.  
  67.    IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
  68. WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
  69. REDISTRIBUTE THE PROGRAMS AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
  70. DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
  71. DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAMS
  72. (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
  73. INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
  74. THE PROGRAMS TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER
  75. OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
  76.  
  77. System requirements
  78. *******************
  79.  
  80.        ClipHistory have very modest system requirements. It needs OS
  81. 2.04 or better, although OS 3.0 or better will make ClipHistory
  82. operate slightly better.
  83.  
  84.    If you have ReqTools (by Nico François) installed, then
  85. ClipHistory will use ReqTools for its requesters (you can disable
  86. this if you like). Otherwise the "normal" system requesters will be
  87. used.
  88.  
  89. Installation
  90. ************
  91.  
  92.        ClipHistory is easy to install. Simply copy the program (and
  93. its icon) to WBStartup, or whereever you find convenient. If you have
  94. OS 2.1 or better, you might want to copy a catalog file as well, to make
  95. ClipHistory operate in another language than english.
  96.  
  97.    The easiest way is to let the Installer do it (if you have it that
  98. is!  :). If not, copy the file cliphistory.catalog as found in the
  99. Catalogs/<language> drawer to Locale:Catalogs/<language> (or to the
  100. drawer Catalogs/<language> in the same drawer as you placed
  101. ClipHistory). In either case, <language> should be one of the
  102. languages you have select in the Locale preferences editor.
  103.  
  104.    If there is no catalog file for your language, please try to fill in
  105. the file Empty.ct in the Catalogs drawer and send it to me. I will
  106. then include the catalog in the next release of ClipHistory. It would
  107. be nice if you could translate the Installer script as well.
  108.  
  109. Usage
  110. *****
  111.  
  112.    To use ClipHistory, you first make sure that the tooltypes are set
  113. up properly. Then start it. You can also start if from a shell, but then
  114. you must remember to Run it (and to write suitable arguments). To
  115. make it permanently installed, simply drop it into WBStartup, or
  116. enter a suitable line in your S:User-Startup file.
  117.  
  118.        ClipHistory installs itself as a commodity, so you can use the
  119. Commodities Exchange program to show the interface, disable/enable
  120. it, or remove it completely. Starting ClipHistory a second time (for
  121. the same clipboard unit (option CLIPUNIT)) will cause the first copy
  122. to show the interface. Pressing the hotkey will also open the interface
  123. (option CX_POPKEY). See Options for more information.
  124.  
  125.    The user interface of ClipHistory is very simple; it contains of a
  126. window with a list gadget. This list contains all the remembered clips.
  127. There is also a menu strip attached (see Menus).
  128.  
  129.    The text showed in the list is either the text - if it is a text
  130. clip - or the type of the IFF clip (everything on the clipboard should
  131. be in IFF format), followed by its size (in bytes). If you have OS 3.0
  132. or higher, the non-text clips will be shown in bold.
  133.  
  134.    To select an item in the list, you either click once on it with the
  135. mouse, or you use the cursur Up/Down keys (optionally with the
  136. Shift/Alt/Ctrl qualifiers) to highlight the requested item.
  137.  
  138.    To copy an item to the clipboard, you double-click on the item, or
  139. press Return when the proper item is selected. Unless the STICKY
  140. option (see Options) have been used, the window will close.
  141.  
  142.    Esc closes the window.
  143.  
  144. Menus
  145. *****
  146.  
  147.    The window ClipHistory opens have the following menus:
  148.  
  149. Project
  150.     About...
  151.           Shows some information about the program and the history.
  152.  
  153.     Hide
  154.           Close the window, but don't quit.
  155.  
  156.     Quit
  157.           Close the window and quit.
  158.  
  159. Edit
  160.     Open clipboard...
  161.           This will open a file requester, allowing you to select a
  162.           file that will be written to the clipboard. If it is an IFF
  163.           file, it will be copied as it is, otherwise it will be
  164.           written as an IFF FTXT file.
  165.  
  166.     Save clipboard as...
  167.           This will open a file requester, allowint you to select a
  168.           filename to which the current clipboard contents will be
  169.           written.
  170.  
  171.     Show clipboard...
  172.           This will write the currently clipboard contents to a
  173.           temprary file, and start the SHOWCLIP program to show this
  174.           file (see Options for more information),
  175.  
  176.     Clear clipboard
  177.           Simply clear the clipboard, by writing a special (and small)
  178.           IFF EMTY file to it.
  179.  
  180. History
  181.     Delete item...
  182.           This will delete the currently selected item. You can also
  183.           press Del to do this.
  184.  
  185.     Delete all items...
  186.           This will delete all clips in the list. You can also press
  187.           Shift-Del to do this.
  188.  
  189.     Save item as...
  190.           This allows you to save the currently selected item to a file
  191.           of your choice.
  192.  
  193.     Show item...
  194.           This will write the currently selected item to a temporary
  195.           file, and start the SHOWCLIP program to show this file (see
  196.           Options for more information),
  197.  
  198. Options
  199.     Create icons?
  200.           If checked, then icons will be created for the files you
  201.           save. This is the same as the option CREATEICONS (see
  202.           Options).
  203.  
  204.     Save text as IFF?
  205.           If checked, then text clips (those that shows up as "normal"
  206.           text in the window) will be saved as IFF files. If you save
  207.           them as normal text, then some information might be lost
  208.           (technical note: all CHRS chunks will be saved, but no
  209.           other(s)). Same as the option TEXTASIFF (see Options).
  210.  
  211.     ReqTools?
  212.           If checked, then ReqTools will be used for requesters, if
  213.           it's available. Same as the option REQTOOLS (see Options).
  214.  
  215. Options
  216. *******
  217.  
  218.    Options can be specified in the tooltypes (when starting from the
  219. Workbench) or on the command line (when starting from a Shell).
  220.  
  221. CX_PRIORITY
  222.      This value specifies the priority ClipHistory will have in the
  223.      commodities input chain. This priority only applies to the hotkey.
  224.      Default is 0. Accpted range is -128 to 127.
  225.  
  226. CX_POPKEY
  227.      This hotkey will open the window. Default is "control lalt c".
  228.      Please refer to your Amiga manual for more information about
  229.      hotkey descriptors.
  230.  
  231. CX_POPUP
  232.      If this option is set to YES, then ClipHistory will open the
  233.      window upon startup (this is the default). Use NO to disable this.
  234.  
  235. CLIPUNIT
  236.      This value specifies the clipboard unit to use. Default is 0.
  237.      Accepted range is 0 to 255.
  238.  
  239.      You can start one copy of ClipHistory for each clipboard unit. In
  240.      Commodities Exchange, the name will be "ClipHistory <unit>",
  241.      where <unit> is the number you specify here.
  242.  
  243.          Note: ClipHistory can be made resident. This is useful if
  244.      you start several copies of ClipHistory, so that all copies
  245.      share the same code (which saves quite a bit of memory).
  246.  
  247. TOOLPRI
  248.      This value specifies the "normal" priority for ClipHistory. To
  249.      make sure that ClipHistory doesn't miss any clips, even if the
  250.      computer is doing much work, you might want to rise the task
  251.      priority of ClipHistory. Default is to use whatever priority
  252.      ClipHistory was started in (this is normally 0). Accepted range is
  253.      -128 to 4.
  254.  
  255.          Note: The Workbench also supports the TOOLPRI tooltype.
  256.      It was added to ClipHistory so that Shell users easily can
  257.      change the priority as well.
  258.  
  259. WORKPRI
  260.      Some operations ClipHistory does can take a little time. Here you
  261.      can specify the priority ClipHistory should use during this
  262.      time, so that other programs can run normally. Usually a negative
  263.      value should be entered. The default is not to change the
  264.      priority. Accepted range is -128 to 4.
  265.  
  266. SILENT
  267.      If this option is set to YES, then ClipHistory won't display any
  268.      requesters or flash the screen for various clip operation errors,
  269.      like when there was a problem reading/writing to the clipboard, or
  270.      when there wasn't enough memory to save a clip. Default is NO.
  271.  
  272. PORTNAME
  273.      This string lets you specify the name of the ARexx port
  274.      ClipHistory opens. The default is "CLIPHISTORYx", where "x" is
  275.      the clipboard unit the history operates on (see CLIPUNIT). If
  276.      you enter an empty string (""), then no ARexx port will be
  277.      opened. If ARexx isn't installed, then no ARexx port will be
  278.      opened either.
  279.  
  280. NEXTKEY
  281.      This hotkey will activate the next item in the history (if
  282.      possible) and paste that one to the clipboard without opening the
  283.      window. Useful when you have snapped a few strings and want to
  284.      paste them somewere. This works even if the window should happen
  285.      to be open. Default is no hotkey ("").
  286.  
  287. PREVKEY
  288.      This hotkey works much like NEXTKEY, but it will paste the
  289.      previous history item (if possible) instead. Default is no hotkey
  290.      ("").
  291.  
  292. AUTOSELECT
  293.      By default, NEXTKEY and PREVKEY will fail (flashing the display
  294.      to inform you about it) if no clip item is selected. If this
  295.      option is set to YES, then NEXTKEY will automatically select the
  296.      first item in the list, and PREVKEY will select the last item.
  297.  
  298. PUBSCREEN
  299.      This string specifies the public screen on which ClipHistory
  300.      should open its window on. Default is the frontmost screen if it
  301.      is public (if OPENONALL is on, it will use the frontmost screen
  302.      anyway), or the default public screen.
  303.  
  304. OPENONALL
  305.      If this option is set to YES, then ClipHistory will open on the
  306.      frontmost screen, regardless if it is public or not. Default is NO.
  307.  
  308.          Note: In order for this to work properly, a function in
  309.      Intuition (CloseScreen()) needs to be patched (this patch is
  310.      only installed if this option have been activated). If some other
  311.      program have patched the same program and you try to exit, then
  312.      ClipHistory will exit anyway, but it will leave a small memory
  313.      allocation, to make sure there aren't any problems. If you have a
  314.      SetMan-like program installed, this should never happen.
  315.  
  316. FONTNAME
  317.      This string specifies the name of the font (including the ".font"
  318.      extension) to use for the window/menus. If not specified, then the
  319.      current screen font is used. You must specify both FONTNAME and
  320.      FONTSIZE.
  321.  
  322.      Hint: If you have MagicWB, it can be a good idea to use e.g.
  323.      XHelvetica, since that font is "complete", i.e. chars than
  324.      normally aren't printable holds graphics to identify the char in
  325.      question.
  326.  
  327. FONTSIZE
  328.      This value specifies the size of the above font. You must specify
  329.      both FONTNAME and FONTSIZE.
  330.  
  331. WINDOWLEFT
  332.      Initial left edge of the window. Default is to center the window
  333.      on the screen.
  334.  
  335. WINDOWTOP
  336.      Initial top edge of the window. Default is to center the window on
  337.      the screen.
  338.  
  339. WINWIDTH
  340.      Initial width of the window. Default is <width of the screen>/2.
  341.  
  342. WINHEIGHT
  343.      Initial height of the window. Default is <height of the screen>/3.
  344.  
  345. STICKY
  346.      If this option is set to YES, then ClipHistory won't close the
  347.      window after writing a clip to the clipboard. Default is NO.
  348.  
  349. SINGLECLICK
  350.      If this option is set to YES, then a single click with the mouse
  351.      on an item is enough to paste it to the clipboard. Click with
  352.      Shift, Alt or Ctrl pressed to select an item without pasting (a
  353.      doubleclick with any qualifier down will also paste). If set to
  354.      NO, a doubleclick is needed to paste the item. A single click with
  355.      any qualifier down will then paste the item. Default is NO.
  356.  
  357. POPSCREEN
  358.      If this option is set to YES, then ClipHistory will - when
  359.      closing its window - restore the screen that was in front before
  360.      the window was opened.  This only needs to be done if that screen
  361.      wasn't public. Default is NO.
  362.  
  363.          Note: Using PUBSCREEN, OPENONALL or STICKY will
  364.      disable this option.
  365.  
  366. SAVEPOS
  367.      If this option is set to YES, then ClipHistory will remember the
  368.      current position of the window when you close it. Otherwise it
  369.      will reopen using the position specified in the arguments (or the
  370.      defaults). Default is NO.
  371.  
  372. SAVESIZE
  373.      If this option is set to YES, then ClipHistory will remember the
  374.      current size of the window when you close it. Otherwise it will
  375.      reopen using the size specified in the arguments (or the
  376.      defaults). Default is NO.
  377.  
  378. MAXCLIPS
  379.      This value specifies the maximum number of clips that the history
  380.      can hold.  Any value accpted. Note that 0 really means 1...
  381.      Default is 32767 (the listview handling routines in the OS can't
  382.      cope with more, so.. :).
  383.  
  384. MAXCLIPSIZE
  385.      If the clip is larger than this value, then it will not be saved
  386.      in the history. Using 0 here will disable the history. Default is
  387.      the MAXMEM limit (see below) if that one is specified. Otherwise
  388.      there is no limit (other than the amount of free memory).
  389.  
  390. MINCLIPSIZE
  391.      If the clip is smaller than this value, then it will not be saved
  392.      in the history. The default is 0.
  393.  
  394.      Please note that this refers to the total size of the clip,
  395.      including the extra overhead due to the IFF file format. For a
  396.      minimal IFF file (as saved by e.g. PowerSnap), this overhead is
  397.      20 bytes. Also, an IFF file is (read: should be) always padded to
  398.      an even number of bytes.  Thus, a relatively useful minimum could
  399.      be 22, which would force each saved clip to have at least 3 data
  400.      bytes (when talking about saved text at least).
  401.  
  402. MAXMEM
  403.      This value specifies how much memory the history may use at most.
  404.      The history is dynamically allocated, using so called memory pools
  405.      (to reduce memory fragmentation). Thus, the actual amount of
  406.      memory used might be a little more than this value. Default is no
  407.      max (other than the amount of free memory).
  408.  
  409. MATCH
  410.      If this option is set to YES, check all new items against the last
  411.      one, and only save the new one if it is different. Default is NO.
  412.  
  413. FULLMATCH
  414.      Like MATCH, but check all entries instead. This option
  415.      overrides MATCH Default is NO.
  416.  
  417.          Warning: This can take some time if you have a large history
  418.      (ClipHistory will use the WORKPRI (see above) during this
  419.      check). If more than one clip is written to the clipboard during
  420.      this time, only the last one will be remembered.
  421.  
  422. CASE
  423.      If this option is set to NO, then ClipHistory will ignore the
  424.      case when comparing two clips (when either MATCH or
  425.      FULLMATCH have been used). Obviously, this is only possible when
  426.      the clip contains text (FTXT). Default is YES.
  427.  
  428. FILTER
  429.      Here you can specify which IFF types that should be saved (or not
  430.      saved, if REJECT have been specified). Space separate the items.
  431.      Case is important. There are many different IFF types available,
  432.      and I can't mention them all, but here is a list over the most
  433.      common ones:
  434.  
  435.     FTXT
  436.           Text. ConClip and PowerSnap saves these ones.
  437.  
  438.     ILBM
  439.           Graphics/palettes. Saved by e.g. IconEdit.
  440.  
  441.     8SVX
  442.           Sound (samples).
  443.  
  444. REJECT
  445.      If this option is set to YES, them the FILTER (see above) will
  446.      reject on a match instead of accept, i.e. it reverses the action
  447.      of the filter.  Default is NO.
  448.  
  449. SHOWCLIP
  450.      This option lets you specify the program to use to view a clip.
  451.      ClipHistory will write the currently selected clip (or the
  452.      contents of the clipboard) to a temporary file, and then start
  453.      this program with the filename as the first argument. Note that
  454.      this file will not be deleted by ClipHistory (you can do this
  455.      with a script if you want to). Default is "MultiView".
  456.  
  457. TEMPDIR
  458.      This option specifies were ClipHistory should write the temprary
  459.      files that the SHOWCLIP program should read and display. Default
  460.      is "T:".
  461.  
  462. FILETYPE
  463.      If this option is specified, then the file type will be the second
  464.      argument to the SHOWCLIP program. This way, a simple Shell
  465.      script can be used to view the file (see the included
  466.      ShowClip script). This argument will be "text" if the clip was
  467.      written as a simple text file (TEXTASIFF is set to NO),
  468.      otherwise the IFF file type will be the second argumet (see
  469.      FILTER for more information about IFF types).  Default is NO.
  470.  
  471. SAVEPATH
  472.      This option lets you specify the directory in which the "Save
  473.      clipboard..."/"Save item..." file requester should open the first
  474.      time (it remembers the last used directory). The default is to
  475.      open in the current directory for ClipHistory
  476.  
  477. TEXTASIFF
  478.      If this option is set to YES then FTXT clips will be saved as an
  479.      IFF file, rather than a normal ASCII-file. All clips that shows up
  480.      as "normal" text in the window are FTXT clips. Note that some
  481.      information may be lost if a clip is saved as ASCII (e.g. font
  482.      information). Default is NO.
  483.  
  484. CREATEICONS
  485.      If this option is set to YES, then an icon will be created for
  486.      each clip that is saved. Default is NO.
  487.  
  488. REQTOOLS
  489.      If this option is set to YES, then ClipHistory will use
  490.      ReqTools for requesters, if it should be available. Default is
  491.      YES.
  492.  
  493. ARexx
  494. *****
  495.  
  496.    As of version 2.0, ClipHistory have an ARexx port. This means
  497. you can access the history and the clipboard from your ARexx
  498. programs. The port is called "CLIPHISTORYx" by default (where x is the
  499. clipboard unit, specified with the CLIPUNIT argument), but you may
  500. change this by using the PORTNAME argument. See Options for more
  501. information.
  502.  
  503. Details
  504. =======
  505.  
  506.    The ARexx commands in ClipHistory are documented in this manner:
  507.  
  508.      GetPrefs PREFS/A => VALUE/N
  509.  
  510.    This line is then followed by an exaplanation of what the command
  511. does.  First on the line is the name of the command (in this example:
  512. GetPrefs). Case is not importand when looking for a command. After
  513. that follows the arguments (in some cases, there are no arguments). The
  514. => arrow indicates that what follows after it is the return value(s)
  515. (a command may return several pieces of information). If no => arrow
  516. is present, then the command returns no information.
  517.  
  518.    The arguments use the standard AmigaDOS template. Thus, the keyword
  519. is optional, but must be specified if the argument doesn't come in the
  520. specified order. The keyword is the text before the / char, and the
  521. character after is a modifier, that tells you a little about this
  522. argument.  The following modifiers are used in this document (there are
  523. others, but they are not used here):
  524.  
  525. /A
  526.      This argument is required. An error is returned if the argument
  527.      isn't specified.
  528.  
  529. /N
  530.      This argument is numeric. It should be a valid decimal number, or
  531.      an error is returned.
  532.  
  533. /S
  534.      This argument is a switch. The precense of this keyword enables a
  535.      flag. If it is not present, the flag is not enabled.
  536.  
  537. /F
  538.      All text following the keyword is taken as the argument, without
  539.      any modifications.
  540.  
  541. /M
  542.      Any number of arguments may be specified here.
  543.  
  544.    These modifiers may be combined, so e.g. /A/N means that a numeric
  545. value must be specified. If no modifier is present, then there are no
  546. special requirements upon the arguments (at least not anything the
  547. argument parser (ReadArgs()) can check).
  548.  
  549.    These modifiers also applies to the return values. But first we need
  550. some more information about the returns. The normal way of returning
  551. information to an ARexx script is to place it in RC (limited to
  552. numeric results, since this also returns errors from the command) or
  553. RESULT (which may contain anything). In ClipHistory (and several other
  554. programs) there is a little more control. Each command that returns
  555. some information also have the two "hidden" (i.e. not documented)
  556. arguments; VAR and STEM. These arguments specify were the return
  557. value should be placed.
  558.  
  559.    The VAR argument specifies in which variable the result should be
  560. placed. This is baiscally the same as to return the value in
  561. RESULT.
  562.  
  563.    The STEM argument is a little different, and is mostly useful for
  564. commands that returns several pieces of information. The argument
  565. specifies the "stem base name" for the return values. Thus, if a
  566. command have the "return template" SIZE/N,ITEMS/N, and we specified
  567. the stem base name TEST., then the variables (stems) TEST.SIZE and
  568. TEST.ITEMS would hold the returns (numeric values). If the return is
  569. in a normal variable, then the different returns will be placed after
  570. each other, separated by spaces.
  571.  
  572.    Now, there is a special return, which use the /M modifier. If we
  573. use the same stem base name as above, and the command have the return
  574. template CLIP/M, then the stem TEST.CLIP.COUNT will hold the number
  575. of strings that are returned, and TEST.CLIP.0, TEST.CLIP.1...
  576. (until TEST.CLIP.x,  where x equals TEST.CLIP.COUNT - 1) will
  577. hold the different strings. If the same information is returned in a
  578. normal variable, then there will first be the count, followed by the
  579. different strings, separated by spaces.
  580.  
  581.    If an argument contains spaces, then it usually needs to be "double
  582. quoted", like this:
  583.  
  584.      '"This is a quoted string"'
  585.  
  586. This is needed since ARexx first removes the single quotes (') when
  587. it parses the string. ClipHistory also needs quotes, to be able to
  588. separate the arguments (these quotes must use the " char).
  589.  
  590.    Negative values needs to be quoted (e.g. '-1'). This is also true
  591. for strings (e.g. file names) that contain a : char.
  592.  
  593.    If an error occured, the variable RC2 will usually hold an error
  594. message or a number (a dos error code. You can use Fault to get an
  595. explanation for a certain number). Note that "OPTIONS RESULTS" must
  596. have be used in the script for this to happen.
  597.  
  598.    All commands sets RC to 10 for an error, 5 for a warning (e.g.
  599. asking for a clip item that doesn't exist, or trying to do a window
  600. operation when the window isn't open), and 0 for all ok.
  601.  
  602.    The ARexx interface in ClipHistory was originally developed
  603. using ARexxBox. The generated code was then modified in several ways
  604. to get it smaller (without loosing any functionality).
  605.  
  606. General commands
  607. ================
  608.  
  609. About
  610.      Simply open the about window. It will open on the same screen as
  611.      the main window, or on the default public screen.
  612.  
  613. CxActivate
  614.      Activate the Commodities interface. Similar to the "Active"
  615.      gadget in the Exchange program. Returns 5 if the interface
  616.      already was active.
  617.  
  618. CxInactivate
  619.      Similar to CxActivate, but inactivate the interface instead.
  620.  
  621. GetPrefs PREFS/A => VALUE/N
  622.      Get the state of the specified preferences item. Currently, the
  623.      following items may be specified:
  624.  
  625.     ICONS
  626.           The "Create icons?" menu item (CREATEICONS argument).
  627.  
  628.     REQTOOLS
  629.           The "ReqTools?" menu item (REQTOOLS argument).
  630.  
  631.     TEXTASIFF
  632.           The "Text as IFF?" menu item (TEXTAIFF argument).
  633.  
  634.      Currently, the value is set to 1 if the flag is set, or 0 if the
  635.      flag isn't set.
  636.  
  637. LockGUI
  638.      Lock the GUI, so that no input can be made (output can still me
  639.      made).  These calls nest, so remember to match them properly.
  640.  
  641. Quit
  642.      Quit ClipHistory. No confirmation requester will be shown.
  643.  
  644. Show PUBSCREEN
  645.      Open the GUI. If a PUBSCREEN argument is specified, then
  646.      ClipHistory will try to open on the specified public screen.
  647.  
  648. UnlockGUI
  649.      Decrease the nesting count for the GUI lock. If we reach zero,
  650.      unlock the GUI, re-enabling user input.
  651.  
  652. SetPrefs PREFS/A,VALUE/A/N
  653.      Set the state of the specified preferences item. Currently, the
  654.      following items may be specified:
  655.  
  656.     ICONS
  657.           The "Create icons?" menu item (CREATEICONS argument).
  658.  
  659.     REQTOOLS
  660.           The "ReqTools?" menu item (REQTOOLS argument).
  661.  
  662.     TEXTASIFF
  663.           The "Text as IFF?" menu item (TEXTAIFF argument).
  664.  
  665.      If the value is 1, then the flag is set, or if it is 0, the flag
  666.      is cleared.
  667.  
  668. History commands
  669. ================
  670.  
  671. DeleteAllItems FORCE/S
  672.      Delete all items in the history. Use FORCE to disable the
  673.      confirmation requester. Returns 5 if the user cancelled the delete.
  674.  
  675. DeleteItem ITEM/N,FORCE/S
  676.      Delete the specified item, or the currently selected if none was
  677.      specified.  Use FORCE to disable the confirmation requester.
  678.      Returns 5 if the user cancelled the requester, or the specified
  679.      item didn't exist.
  680.  
  681. GetTextItem ITEM/N => CLIP/M
  682.      Return the contents of the specified item, of if not specified, the
  683.      currently selected item. If the clip doesn't contain any text,
  684.      return 5 in RC. The CLIP array will hold the different CHRS
  685.      chunks.  Usually, there is only one.
  686.  
  687. GetSelected => ITEM/N
  688.      Returns the currently selected item, or -1 if no item is selected.
  689.  
  690. ItemInfo ITEM/N => TYPE,SIZE/N,NUMCHRS/N
  691.      Return some information about the specified item, or the currently
  692.      selected item if no argument is given. The follwing information is
  693.      returned:
  694.  
  695.     TYPE
  696.           The type of the IFF file, usually FTXT, ILBM or 8SVX.
  697.  
  698.     SIZE/N
  699.           The size of the clip, in bytes.
  700.  
  701.     NUMCHRS/N
  702.           The number of so called CHRS chunks in the clip. If 0, then
  703.           the clip doesn't contain any text.
  704.  
  705. HistoryInfo => ITEMS/N,SIZE/N
  706.      Returns the following information about the history:
  707.  
  708.     ITEMS/N
  709.           Number of items currently in the history
  710.  
  711.     SIZE/N
  712.           The total size of the history, in bytes.
  713.  
  714. LockHistory
  715.      Lock the history, so that no items can be added to it. These calls
  716.      nest, so remember to match them properly.
  717.  
  718. PutItem ITEM/N
  719.      Write the specified or currently selected item to the clipboard.
  720.  
  721. SaveItemAs NAME,ITEM/N,REQUEST/S
  722.      Save the specified or currently selected item to the specified
  723.      file. If no file name is specified, or the REQUEST flag is used,
  724.      show a requester to let the user specify the name.
  725.  
  726. SelectItem ITEM/N,RELATIVE/S
  727.      Select the specified item. If the RELATIVE flag is used, add the
  728.      ITEM to the currently selected item number (there must be a
  729.      selected item for this to work).
  730.  
  731. ShowItem ITEM/N
  732.      Show the specified, or currently selected item. See SHOWCLIP in
  733.      the Options chapter for more information about this.
  734.  
  735. UnlockHistory
  736.      Decrease the nesting count for the history lock. If we reach zero,
  737.      unlock the history, re-enabling new items to be added.
  738.  
  739. Clipboard commands
  740. ==================
  741.  
  742. ClearClipboard
  743.      Clear the clipboard, by writing a special "empty" IFF-file to it.
  744.  
  745. GetTextClip => CLIP/M
  746.      Return the contents of the clipboard. If the clipboard doesn't
  747.      contain any text, return 5 in RC. The CLIP array will hold the
  748.      CHRS chunks. Usually, there will only be one.
  749.  
  750. PutFile NAME,REQUEST/S
  751.      Place the named file on the clipboard. If no name is given, or the
  752.      REQUEST flag is set, open a requester for the user to select a
  753.      file.  If the file is an IFF file, it will be copied to the
  754.      clipboard.  Otherwise, ClipHistory assumes the file contains
  755.      text, and will write it as an IFF FTXT file.
  756.  
  757. PutText TEXT/A/F
  758.      Put the specified text on the clipboard, as an IFF FTXT file.
  759.  
  760. SaveClipAs NAME,ITEM/N,REQUEST/S
  761.      Save the clipboard contents to the specified file. If no file name
  762.      is specified, or the REQUEST flag is used, show a requester to let
  763.      the user specify the name.
  764.  
  765. ShowClip
  766.      Show the file in the clipboard. See the SHOWCLIP argument in the
  767.      Options chapter for more information about this.
  768.  
  769. Requester commands
  770. ==================
  771.  
  772. RequestFile TITLE,PATH,FILE,PATTERN => FILE
  773.      Show a file requester, with the specified title, default path and
  774.      file, and the specified pattern, and return the selected name
  775.      (FILE). If the requester is cancelled, return 5 in RC.
  776.  
  777. RequestNotify PROMPT/A
  778.      Show the specified prompt in a requester with a single " Ok "
  779.      gadget.
  780.  
  781. RequestResponse TITLE,PROMPT/A,GADGETS
  782.      Show the specified prompt, with the specified title in a requester
  783.      with an " Ok " and a "Cancel" gadget. Returns 0 if cancel was
  784.      selected, or 5 if ok was selected.
  785.  
  786.      The GADGETS option allows you to specify your own gadgets. The
  787.      diffenret gadgets should be separated by "|" chars. Returns 0 for
  788.      the rightmost gadget, 1 for the leftmost, 2 for the next, and so
  789.      on...
  790.  
  791. Window commands
  792. ===============
  793.  
  794. ActivateWindow
  795.      Activates the main window.
  796.  
  797. ChangeWindow LEFTEDGE/N,TOPEDGE/N,WIDTH/N,HEIGHT/N
  798.      Move and resize the window to the given coordinates, or as close as
  799.      possible. '-1' for a given coordinate means "don't change this
  800.      one".
  801.  
  802. Hide
  803.      Simply close the window.
  804.  
  805. IsOpen => OPEN/N
  806.      Returns 1 if the window is open, or 0 if it isn't.
  807.  
  808. MoveWindow LEFTEDGE/N,TOPEDGE/N
  809.      Similar to ChangeWindow, but this command only lets you change
  810.      the position of the window.
  811.  
  812. SizeWindow WIDTH/N,HEIGHT/N
  813.      Similar to ChangeWindow, but this command only lets you change
  814.      the size of the window.
  815.  
  816. UnZoomWindow
  817.      If the window is zoomed, then unzoom it (possibly making it
  818.      larger).
  819.  
  820. WindowToBack
  821.      Simply move the window behind any other window(s), if possible.
  822.  
  823. WindowToFront
  824.      Simply move the window in front of any other window(s), if
  825.      possible.
  826.  
  827. ZoomWindow
  828.      If the window isn't zoomed, then zoom it (possibly making it
  829.      smaller).
  830.  
  831. Future
  832. ******
  833.  
  834.    There are a few things I might add to ClipHistory:
  835.  
  836.    *  More IFF parsing. Now it is minimal, only reading/writing exactly
  837.      what is on the clipboard, with a minor "support" for FTXT.
  838.      Enhanced parsing could e.g. reduce the overhead for FTXT clips, by
  839.      only saving the actual text.
  840.  
  841.    *  Separate accept and reject filters. I would need to alter the way
  842.      they are specified though (now I'm using ReadArgs() "/M"
  843.      specifier for this, and ReadArgs() don't like several "/M"
  844.      specifiers in one template.. :).
  845.  
  846.    *  Load/save of the entire history. I don't see much use for this
  847.      feature (and I've heard that there are very few programs that are
  848.      able to process such a file! :)
  849.  
  850.    *  Prefs window, to edit/save the settings. Perhaps as a separate
  851.      prefs program.
  852.  
  853.    *  Some other way of "highlighting" non-text clips on OS 3.0 or
  854.      better. The problem is that I don't know how I should change it.
  855.      :) Please tell me if you have any idea.
  856.  
  857.    *  Make a version using Triton (or some other layout engine).
  858.  
  859.    None of these things are important for me, but feel free to send me
  860. a note telling me what *you* would like to see added (see Author
  861. contact).
  862.  
  863. Author contact
  864. **************
  865.  
  866.    Feel free to send comments, bug reports (detailed ones, please),
  867. translations, money or whatever, to:
  868.  
  869.      S-mail:  Magnus Holmgren
  870.               Kvarnbergsvägen 5
  871.               S-444 47  Stenungsund
  872.               SWEDEN
  873.      
  874.      E-mail:  cmh@augs.se (internet) or 2:204/404.6 (fidonet).
  875.  
  876.    (Note: The old S-mail (S=Snail :) address should not be used,
  877. although mail sent to that address should reach me (but not after
  878. August 1995))
  879.  
  880. Acknowledgements
  881. ****************
  882.  
  883.    Thanks go to the following persons, for helping me in some way with
  884. this program:
  885.  
  886. Nico François
  887.      His program PowerSnap inspired me do write this program in the
  888.      first place. He also sent me a few small (but useful) functions,
  889.      and came with a few suggestions/bug reports.
  890.  
  891. Nikolai Waldman
  892.      Suggestions.
  893.  
  894. Michael Berg
  895.      Bug report and suggestions.
  896.  
  897. Lars Eilebrecht
  898.      German translation.
  899.  
  900. Georges Concalves
  901.      French translation and MagicWB icon.
  902.  
  903. Kenneth Fribert
  904.      Danish translation.
  905.  
  906. Michael Balzer
  907.      For ARexxBox, which was used as a base for the ARexx interface
  908.      (the code have been modified a "little".. Saved ~5 Kb from the
  909.      program! :).
  910.  
  911. Olaf Barthel
  912.      For the "menu glyph" code from term.
  913.  
  914. Program history
  915. ***************
  916.  
  917. Version 1.0:
  918.      Initial release.
  919.  
  920. Version 1.1:
  921.         *  Removed some debugging code.
  922.  
  923.         *  Added the SINGLECLICK flag. If YES, a single click on an
  924.           item is enough to paste it to the clipboard. Use
  925.           shift/alt/ctrl to select an item without pasting (a
  926.           doubleclick with any qualifier down will also paste). If set
  927.           to NO, a single click with any qualifier down will also paste
  928.           the item.
  929.  
  930.         *  Recompiled with DICE 3.0.
  931.  
  932.         *  German catalog added. Unfortunately I don't have the source
  933.           for it.. :)
  934.  
  935. Version 2.0:
  936.         *  ARexx-port with over 40 commands added.
  937.  
  938.         *  ClipHistory is now residentable! It wasn't that easy... :)
  939.           (try yourself with DICE, a couple of callback hooks and a
  940.           patch! :)
  941.  
  942.         *  French catalog and installer script by Georges Goncalves
  943.           included.
  944.  
  945.         *  Danish catalog by Kenneth Fribert included.
  946.  
  947.         *  German catalog source included.
  948.  
  949.         *  MagicWB icon by Georges Concalves included.
  950.  
  951.         *  Added menu items to load/save/view/clear the current
  952.           clipboard contents.  You can also view an item in the history.
  953.  
  954.         *  Any font specified in the tooltypes needed to be in memory
  955.           for ClipHistory to find it. Now it will try to load it from
  956.           disk if possible.
  957.  
  958.         *  If the screenfont or the font specified in the tooltypes
  959.           didn't open, ClipHistory will now use the system default
  960.           font instead (rather than topaz/8).
  961.  
  962.         *  Added the following arguments: PORTNAME, NEXTKEY,
  963.           PREVKEY, AUTOSELECT, SHOWCLIP, TEMPDIR, FILETYPE,
  964.           and SAVEPATH. See Options.
  965.  
  966.         *  ClipHistory will now always exit even if someone have
  967.           overpatched the function ClipHistory may patch. If the
  968.           patch was overpatched, there will be a small memory loss.
  969.  
  970.         *  When doing a full check, and a match is found, then
  971.           ClipHistory will select the item that matched, so that the
  972.           selected item reflects the current clipboard contents. In
  973.           general, ClipHistory will do its best to keep the selected
  974.           item up to date. This includes deselecting any item if no item
  975.           in the history matches the current clipboard contents (e.g. a
  976.           paste was filtered out)
  977.  
  978.         *  ClipHistory will now use the OS 3.0 wait pointer when
  979.           needed.
  980.  
  981.         *  SysIHack "support" added (i.e. it handles
  982.           larger-than-normal window size gadgets properly).
  983.  
  984.         *  The window will now backfill with the current background
  985.           color, rather than color 0.
  986.  
  987.         *  The "Settings/Create icons" menu item was not working, in
  988.           that icons never got created. I had written a function to do
  989.           it, but it wasn't used anywere! :)
  990.  
  991.         *  Non-FTXT clips are now shown in real bold (if possible).
  992.  
  993.         *  When deleting a single item, a new item will be selected, if
  994.           possible.
  995.  
  996. Version 2.1:
  997.         *  The selected item wasn't always visible when the window
  998.           opened.
  999.  
  1000.         *  Removed Enforcer hits when data was written to the
  1001.           clipboard and the window wasn't open.
  1002.  
  1003. Version 2.2:
  1004.         *  When copying a non-text clip from the clipboard to a file,
  1005.           then ClipHistory would read innocent memory, and generate
  1006.           an incorrect (and often a very large) file.
  1007.  
  1008.         *  More tweeking of the ARexx code. Made it somewhat smaller,
  1009.           and changed some other code to be more tolerant (e.g., stem
  1010.           base names no longer require a '.' char at the end. If not
  1011.           present, it will be added).
  1012.  
  1013.         *  Made a few minor fixes to the example ARexx-script.
  1014.  
  1015.         *  Added scaled menu glyphs (OS 3.0+ only), based on source
  1016.           code from term.
  1017.  
  1018.         *  Date in About requester localized. :)
  1019.  
  1020.         *  The ReqTools file requester didn't open in the right
  1021.           drawer.
  1022.  
  1023.